home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / Xm / XmParseMapping.z / XmParseMapping
Encoding:
Text File  |  2002-10-03  |  16.8 KB  |  265 lines
  1.  
  2.  
  3.  
  4.      XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnngggg((((3333XXXX))))        UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV        XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnngggg((((3333XXXX))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.           XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnngggg - Data type for a compound string parse
  10.           mapping
  11.  
  12.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.           #include <Xm/Xm.h>
  14.  
  15.      VVVVEEEERRRRSSSSIIIIOOOONNNN
  16.           This page documents Motif 2.1.
  17.  
  18.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  19.           XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnngggg is an opaque data type for a parse mapping
  20.           used by XXXXmmmmSSSSttttrrrriiiinnnnggggPPPPaaaarrrrsssseeeeTTTTeeeexxxxtttt to create a compound string.  A
  21.           parse mapping contains a pattern to be matched in text being
  22.           parsed to create a compound string.  It also contains a
  23.           compound string, or a function to be invoked to provide a
  24.           compound string, to be included in the compound string being
  25.           created whenever the pattern is matched.
  26.  
  27.           An application uses a resource-style interface to specify
  28.           components for an XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnngggg.  XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnnggggCCCCrrrreeeeaaaatttteeee
  29.           creates a parse mapping, using a resource-style argument
  30.           list.  XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnnggggGGGGeeeettttVVVVaaaalllluuuueeeessss and XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnnggggSSSSeeeettttVVVVaaaalllluuuueeeessss
  31.           retrieve and set the components of a parse mapping.
  32.           XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnnggggFFFFrrrreeeeeeee recovers memory used by a parse mapping.
  33.           XXXXmmmmPPPPaaaarrrrsssseeeeTTTTaaaabbbblllleeee is an array of XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnngggg objects.
  34.  
  35.           The XXXXmmmmNNNNiiiinnnnvvvvooookkkkeeeePPPPaaaarrrrsssseeeePPPPrrrroooocccc resource is a function of type
  36.           XXXXmmmmPPPPaaaarrrrsssseeeePPPPrrrroooocccc, which is defined as follows:
  37.  
  38.           XmIncludeStatus (*XmParseProc) (_t_e_x_t__i_n__o_u_t, _t_e_x_t__e_n_d, _t_y_p_e, _t_a_g, _e_n_t_r_y, _p_a_t_t_e_r_n__l_e_n_g_t_h,
  39.           _s_t_r__i_n_c_l_u_d_e, _c_a_l_l__d_a_t_a)
  40.                   XtPointer *_t_e_x_t__i_n__o_u_t;
  41.                   XtPointer _t_e_x_t__e_n_d;
  42.                   XmTextType _t_y_p_e;
  43.                   XmStringTag _t_a_g;
  44.                   XmParseMapping _e_n_t_r_y;
  45.                   int _p_a_t_t_e_r_n__l_e_n_g_t_h;
  46.                   XmString *_s_t_r__i_n_c_l_u_d_e;
  47.                   XtPointer _c_a_l_l__d_a_t_a;
  48.  
  49.           A parse procedure provides an escape mechanism for
  50.           arbitrarily complex parsing.  This procedure is invoked when
  51.           a pattern in the input text is matched with a pattern in a
  52.           parse mapping whose XXXXmmmmNNNNiiiinnnncccclllluuuuddddeeeeSSSSttttaaaattttuuuussss is XXXXmmmmIIIINNNNVVVVOOOOKKKKEEEE.
  53.  
  54.           The input text is a pointer to the first byte of the pattern
  55.           that was matched to trigger the call to the parse procedure.
  56.           The parse procedure consumes as many bytes of the input
  57.           string as it needs and sets the input text pointer to the
  58.           following byte.  It returns a compound string to be included
  59.           in the compound string being constructed, and it also
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 10/3/02)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnngggg((((3333XXXX))))        UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV        XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnngggg((((3333XXXX))))
  71.  
  72.  
  73.  
  74.           returns an XXXXmmmmIIIInnnncccclllluuuuddddeeeeSSSSttttaaaattttuuuussss indicating how the returned
  75.           compound string should be handled.  If the parse procedure
  76.           does not set the input text pointer ahead by at least one
  77.           byte, the parsing routine continues trying to match the
  78.           input text with the patterns in the remaining parse mappings
  79.           in the parse table.  Otherwise, the parsing routine begins
  80.           with the new input text pointer and tries to match the input
  81.           text with patterns in the parse mappings starting at the
  82.           beginning of the parse table.
  83.  
  84.           _t_e_x_t__i_n__o_u_t
  85.                     Specifies the text being parsed.  The value is a
  86.                     pointer to the first byte of text matching the
  87.                     pattern that triggered the call to the parse
  88.                     procedure.  When the parse procedure returns, this
  89.                     argument is set to the position in the text where
  90.                     parsing should resume-that is, to the byte
  91.                     following the last character parsed by the parse
  92.                     procedure.
  93.  
  94.           _t_e_x_t__e_n_d  Specifies a pointer to the end of the _t_e_x_t__i_n__o_u_t
  95.                     string.  If _t_e_x_t__e_n_d is NULL, the string is
  96.                     scanned until a NULL character is found.
  97.                     Otherwise, the string is scanned up to but not
  98.                     including the character whose address is _t_e_x_t__e_n_d.
  99.  
  100.           _t_y_p_e      Specifies the type of text and the tag type.  If a
  101.                     locale tag should be created, _t_y_p_e has a value of
  102.                     either XXXXmmmmMMMMUUUULLLLTTTTIIIIBBBBYYYYTTTTEEEE____TTTTEEEEXXXXTTTT or XXXXmmmmWWWWIIIIDDDDEEEECCCCHHHHAAAARRRR____TTTTEEEEXXXXTTTT.  If a
  103.                     charset should be created, _t_y_p_e has a value of
  104.                     XXXXmmmmCCCCHHHHAAAARRRRSSSSEEEETTTT____TTTTEEEEXXXXTTTT.
  105.  
  106.           _t_a_g       Specifies the tag to be used in creating the
  107.                     result.  The type of string tag created (charset
  108.                     or locale) depends on the text type and the passed
  109.                     in _t_a_g value.  If the _t_a_g value is NULL and if
  110.                     _t_y_p_e indicates that a charset string tag should be
  111.                     created, the string tag has the value that is the
  112.                     result of mapping XXXXmmmmSSSSTTTTRRRRIIIINNNNGGGG____DDDDEEEEFFFFAAAAUUUULLLLTTTT____CCCCHHHHAAAARRRRSSSSEEEETTTT.  If
  113.                     _t_y_p_e indicates a locale string tag, the string tag
  114.                     has the value ____MMMMOOOOTTTTIIIIFFFF____DDDDEEEEFFFFAAAAUUUULLLLTTTT____LLLLOOOOCCCCAAAALLLLEEEE.
  115.  
  116.           _e_n_t_r_y     Specifies the parse mapping that triggered the
  117.                     call to the parse procedure.
  118.  
  119.           _p_a_t_t_e_r_n__l_e_n_g_t_h
  120.                     Specifies the number of bytes in the input text,
  121.                     following _t_e_x_t__i_n__o_u_t, that constitute the matched
  122.                     pattern.
  123.  
  124.           _s_t_r__i_n_c_l_u_d_e
  125.                     Specifies a pointer to a compound string.  The
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 10/3/02)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnngggg((((3333XXXX))))        UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV        XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnngggg((((3333XXXX))))
  137.  
  138.  
  139.  
  140.                     parse procedure creates a compound string to be
  141.                     included in the compound string being constructed.
  142.                     The parse procedure then returns the compound
  143.                     string in this argument.
  144.  
  145.           _c_a_l_l__d_a_t_a Specifies data passed by the application to the
  146.                     parsing routine.
  147.  
  148.           The parse procedure returns an XXXXmmmmIIIInnnncccclllluuuuddddeeeeSSSSttttaaaattttuuuussss indicating
  149.           how _s_t_r__i_n_c_l_u_d_e is to be included in the compound string
  150.           being constructed.  Following are the possible values:
  151.  
  152.           XXXXmmmmIIIINNNNSSSSEEEERRRRTTTT  Concatenate the result to the compound string
  153.                     being constructed and continue parsing.
  154.  
  155.           XXXXmmmmTTTTEEEERRRRMMMMIIIINNNNAAAATTTTEEEE
  156.                     Concatenate the result to the compound string
  157.                     being constructed and terminate parsing.
  158.  
  159.         NNNNeeeewwww RRRReeeessssoooouuuurrrrcccceeeessss
  160.           The following table defines a set of resources used by the
  161.           programmer to specify data.  The codes in the access column
  162.           indicate if the given resource can be set at creation time
  163.           (C), set by using XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnnggggSSSSeeeettttVVVVaaaalllluuuueeeessss (S), retrieved by
  164.           using XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnnggggGGGGeeeettttVVVVaaaalllluuuueeeessss (G), or is not applicable
  165.           (N/A).
  166.  
  167.                                XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnngggg RRRReeeessssoooouuuurrrrcccceeee SSSSeeeetttt
  168.           NNNNaaaammmmeeee                 CCCCllllaaaassssssss   TTTTyyyyppppeeee              DDDDeeeeffffaaaauuuulllltttt          AAAAcccccccceeeessssssss
  169.           XmNclientData                XtPointer         NULL             CSG
  170.           XmNincludeStatus             XmIncludeStatus   XmINSERT         CSG
  171.           XmNinvokeParseProc           XmParseProc       NULL             CSG
  172.           XmNpattern                   XtPointer         NULL             CSG
  173.           XmNpatternType               XmTextType        XmCHARSET_TEXT   CSG
  174.           XmNsubstitute                XmString          NULL             CSG
  175.  
  176.           XXXXmmmmNNNNcccclllliiiieeeennnnttttDDDDaaaattttaaaa
  177.                     Specifies data to be used by the parse procedure.
  178.  
  179.           XXXXmmmmNNNNiiiinnnncccclllluuuuddddeeeeSSSSttttaaaattttuuuussss
  180.                     Specifies how the result of the mapping is to be
  181.                     included in the compound string being constructed.
  182.                     Unless the value is XXXXmmmmIIIINNNNVVVVOOOOKKKKEEEE, the result of the
  183.                     mapping is the value of XXXXmmmmNNNNssssuuuubbbbssssttttiiiittttuuuutttteeee.  Following
  184.                     are the possible values for XXXXmmmmNNNNiiiinnnncccclllluuuuddddeeeeSSSSttttaaaattttuuuussss:
  185.  
  186.                     XXXXmmmmIIIINNNNSSSSEEEERRRRTTTT  Concatenate the result to the compound
  187.                               string being constructed and continue
  188.                               parsing.
  189.  
  190.                     XXXXmmmmIIIINNNNVVVVOOOOKKKKEEEE  Invoke the XXXXmmmmNNNNiiiinnnnvvvvooookkkkeeeePPPPaaaarrrrsssseeeePPPPrrrroooocccc on the
  191.                               text being parsed and use the returned
  192.  
  193.  
  194.  
  195.      Page 3                                          (printed 10/3/02)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnngggg((((3333XXXX))))        UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV        XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnngggg((((3333XXXX))))
  203.  
  204.  
  205.  
  206.                               compound string instead of XXXXmmmmNNNNssssuuuubbbbssssttttiiiittttuuuutttteeee
  207.                               as the result to be inserted into the
  208.                               compound string being constructed.  The
  209.                               include status returned by the parse
  210.                               procedure (XXXXmmmmIIIINNNNSSSSEEEERRRRTTTT or XXXXmmmmTTTTEEEERRRRMMMMIIIINNNNAAAATTTTEEEE)
  211.                               determines how the returned compound
  212.                               string is included.
  213.  
  214.                     XXXXmmmmTTTTEEEERRRRMMMMIIIINNNNAAAATTTTEEEE
  215.                               Concatenate the result to the compound
  216.                               string being constructed and terminate
  217.                               parsing.
  218.  
  219.           XXXXmmmmNNNNiiiinnnnvvvvooookkkkeeeePPPPaaaarrrrsssseeeePPPPrrrroooocccc
  220.                     Specifies the parse procedure to be invoked when
  221.                     XXXXmmmmNNNNiiiinnnncccclllluuuuddddeeeeSSSSttttaaaattttuuuussssis XXXXmmmmIIIINNNNVVVVOOOOKKKKEEEE.
  222.  
  223.           XXXXmmmmNNNNppppaaaatttttttteeeerrrrnnnn
  224.                     Specifies a pattern to be matched in the text
  225.                     being parsed.  This is a maximum of one character.
  226.  
  227.           XXXXmmmmNNNNppppaaaatttttttteeeerrrrnnnnTTTTyyyyppppeeee
  228.                     Specifies the type of the pattern that is the
  229.                     value of XXXXmmmmNNNNppppaaaatttttttteeeerrrrnnnn.  Following are the possible
  230.                     values:
  231.  
  232.                        +o  XXXXmmmmCCCCHHHHAAAARRRRSSSSEEEETTTT____TTTTEEEEXXXXTTTT
  233.  
  234.                        +o  XXXXmmmmMMMMUUUULLLLTTTTIIIIBBBBYYYYTTTTEEEE____TTTTEEEEXXXXTTTT
  235.  
  236.                        +o  XXXXmmmmWWWWIIIIDDDDEEEECCCCHHHHAAAARRRR____TTTTEEEEXXXXTTTT
  237.  
  238.           XXXXmmmmNNNNssssuuuubbbbssssttttiiiittttuuuutttteeee
  239.                     Specifies the compound string to be included in
  240.                     the compound string being constructed when
  241.                     XXXXmmmmNNNNiiiinnnncccclllluuuuddddeeeeSSSSttttaaaattttuuuussss is XXXXmmmmIIIINNNNSSSSEEEERRRRTTTT or XXXXmmmmTTTTEEEERRRRMMMMIIIINNNNAAAATTTTEEEE.
  242.  
  243.      RRRREEEELLLLAAAATTTTEEEEDDDD
  244.           XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnnggggCCCCrrrreeeeaaaatttteeee(3), XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnnggggFFFFrrrreeeeeeee(3),
  245.           XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnnggggGGGGeeeettttVVVVaaaalllluuuueeeessss(3), XXXXmmmmPPPPaaaarrrrsssseeeeMMMMaaaappppppppiiiinnnnggggSSSSeeeettttVVVVaaaalllluuuueeeessss(3),
  246.           XXXXmmmmPPPPaaaarrrrsssseeeeTTTTaaaabbbblllleeee(3), and XXXXmmmmSSSSttttrrrriiiinnnngggg(3).
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.      Page 4                                          (printed 10/3/02)
  262.  
  263.  
  264.  
  265.